{
  "nbformat": 4,
  "nbformat_minor": 5,
  "metadata": {},
  "cells": [
    {
      "metadata": {},
      "source": [
        "<td>\n",
        "   <a target=\"_blank\" href=\"https://labelbox.com\" ><img src=\"https://labelbox.com/blog/content/images/2021/02/logo-v4.svg\" width=190/></a>\n",
        "</td>"
      ],
      "cell_type": "markdown"
    },
    {
      "metadata": {},
      "source": [
        "<td>\n",
        "<a href=\"https://colab.research.google.com/github/Labelbox/labelbox-python/blob/master/examples/basics/basics.ipynb\" target=\"_blank\"><img\n",
        "src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"></a>\n",
        "</td>\n",
        "\n",
        "<td>\n",
        "<a href=\"https://github.com/Labelbox/labelbox-python/tree/master/examples/basics/basics.ipynb\" target=\"_blank\"><img\n",
        "src=\"https://img.shields.io/badge/GitHub-100000?logo=github&logoColor=white\" alt=\"GitHub\"></a>\n",
        "</td>"
      ],
      "cell_type": "markdown"
    },
    {
      "metadata": {},
      "source": [
        "# Basic project/datasets overview\n",
        "\n",
        "This notebook is used to go over the basic of the Python SDK, such as what a db object is, and how to interact with it. \n",
        "\n"
      ],
      "cell_type": "markdown"
    },
    {
      "metadata": {},
      "source": [
        "!pip install labelbox"
      ],
      "cell_type": "code",
      "outputs": [],
      "execution_count": null
    },
    {
      "metadata": {},
      "source": [
        "import labelbox as lb\n",
        "import random"
      ],
      "cell_type": "code",
      "outputs": [],
      "execution_count": null
    },
    {
      "metadata": {},
      "source": [
        "# API Key and Client\n",
        "Provide a valid api key below in order to properly connect to the Labelbox Client."
      ],
      "cell_type": "markdown"
    },
    {
      "metadata": {},
      "source": [
        "# Add your api key\n",
        "API_KEY=None\n",
        "# To get your API key go to: Workspace settings -> API -> Create API Key\n",
        "client = lb.Client(api_key=API_KEY)"
      ],
      "cell_type": "code",
      "outputs": [],
      "execution_count": null
    },
    {
      "metadata": {},
      "source": [
        "# For the purpose of this demo get a single project/dataset id from your organization\n",
        "\n",
        "# Get a single Project id\n",
        "# get_projects returns a PaginatedCollection object, which is iterable. \n",
        "project = next(client.get_projects())\n",
        "project_id=project.uid\n",
        "project_name=project.name\n",
        "print(\"Project ID: \", project_id)\n",
        "print(\"Project Name:\", project_name)\n",
        "\n",
        "print(\"-\" * 40)\n",
        "\n",
        "# Get a single dataset id\n",
        "# get_datasets returns a PaginatedCollection object, which is iterable. \n",
        "dataset = next(client.get_datasets())\n",
        "dataset_id = dataset.uid\n",
        "dataset_name = dataset.name\n",
        "print(\"Dataset ID: \", dataset_id)\n",
        "print(\"Dataset Name:\" , dataset_name)"
      ],
      "cell_type": "code",
      "outputs": [],
      "execution_count": null
    },
    {
      "metadata": {},
      "source": [
        "# Fetch the project and dataset by using the IDs fetched in the previous cell\n",
        "project = client.get_project(project_id)\n",
        "dataset = client.get_dataset(dataset_id)"
      ],
      "cell_type": "code",
      "outputs": [],
      "execution_count": null
    },
    {
      "metadata": {},
      "source": [
        "print(\"Project: \", project)\n",
        "print(\"Dataset: \", dataset)"
      ],
      "cell_type": "code",
      "outputs": [],
      "execution_count": null
    },
    {
      "metadata": {},
      "source": [
        "### Fields\n",
        "* All db objects have fields (look at the source code to see them https://github.com/Labelbox/labelbox-python/blob/develop/labelbox/schema/project.py)\n",
        "* These fields are attributes of the object"
      ],
      "cell_type": "markdown"
    },
    {
      "metadata": {},
      "source": [
        "print(project.name)\n",
        "print(dataset.name)"
      ],
      "cell_type": "code",
      "outputs": [],
      "execution_count": null
    },
    {
      "metadata": {},
      "source": [
        "* Fields can be updated. This will be reflected server side (you will see it in labelbox) "
      ],
      "cell_type": "markdown"
    },
    {
      "metadata": {},
      "source": [
        "project.update(description=\"new description field\")\n",
        "print(project.description)"
      ],
      "cell_type": "code",
      "outputs": [],
      "execution_count": null
    },
    {
      "metadata": {},
      "source": [
        "### Pagination\n",
        "* Queries that return a list of database objects are return as a PaginatedCollection\n",
        "* Limits the data that is being returned for better performance"
      ],
      "cell_type": "markdown"
    },
    {
      "metadata": {},
      "source": [
        "labels_paginated_collection = project.labels()\n",
        "print(\"Type of collection: \", type(labels_paginated_collection))\n",
        "\n",
        "# A paginated collection can be parsed by using list()\n",
        "# list(paginated...) should be avoided for queries that could return more than a dozen results\n",
        "print(\"Number of labels :\", len(list(labels_paginated_collection)))"
      ],
      "cell_type": "code",
      "outputs": [],
      "execution_count": null
    },
    {
      "metadata": {},
      "source": [
        "# Note that if you selected a `project_id` without any labels this will raise `StopIteration`\n",
        "# Iterate over the paginated collection\n",
        "try: \n",
        "  single_label = next(project.labels())\n",
        "  print(single_label)\n",
        "except StopIteration: \n",
        "  print(\"Project has no labels !\")"
      ],
      "cell_type": "code",
      "outputs": [],
      "execution_count": null
    },
    {
      "metadata": {},
      "source": [
        "### Query parameters\n",
        "* Query with the following conventions:\n",
        "    * `DbObject.Field`"
      ],
      "cell_type": "markdown"
    },
    {
      "metadata": {},
      "source": [
        "datasets = client.get_datasets(where=lb.Dataset.name == dataset_name)\n",
        "\n",
        "projects = client.get_projects(\n",
        "    where=((lb.Project.name == project_name) &\n",
        "           (lb.Project.description == \"new description field\")))\n",
        "\n",
        "# The above two queries return PaginatedCollections because the filter parameters aren't guaranteed to be unique.\n",
        "# So even if there is one element returned it is in a paginatedCollection.\n",
        "print(projects)\n",
        "print(next(projects, None))\n",
        "print(next(projects, None))\n",
        "print(next(projects, None))\n",
        "# We can see there is only one."
      ],
      "cell_type": "code",
      "outputs": [],
      "execution_count": null
    },
    {
      "metadata": {},
      "source": [
        "### Querying Limitations\n",
        "* The DbObject used for the query must be the same as the DbObject returned by the querying function.  \n",
        "* The below query is not valid since get_project returns a project not a dataset\n",
        ">  `>>> projects = client.get_projects(where = lb.Dataset.name == \"dataset_name\")`\n"
      ],
      "cell_type": "markdown"
    },
    {
      "metadata": {},
      "source": [
        "# Relationships between projects and batches/datasets\n",
        "\n"
      ],
      "cell_type": "markdown"
    },
    {
      "metadata": {},
      "source": [
        "sample_project_batches = project.batches()\n",
        "\n",
        "list(sample_project_batches)\n",
        "\n",
        "for b in sample_project_batches:\n",
        "  print(f\" Name of project : {b.project().name}\")\n",
        "  print(f\" Name of batches in project: {b.name}\")"
      ],
      "cell_type": "code",
      "outputs": [],
      "execution_count": null
    }
  ]
}